base-x

What is base-x?

The base-x npm package is designed for encoding and decoding of non-standard base representations. It is commonly used for converting between binary data and a variety of alphanumeric representations using different base encodings, such as base58 used in Bitcoin addresses.

What are base-x's main functionalities?

Encoding binary data to a specified base

This feature allows you to encode binary data (like a Buffer) into a string representation using a custom base alphabet. The example shows encoding 'Hello World' to a base58 string.

"const baseX = require('base-x');\nconst BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';\nconst bs58 = baseX(BASE58);\nconst encoded = bs58.encode(Buffer.from('Hello World'));\nconsole.log(encoded); // Prints encoded string in base58"

Decoding a base-encoded string to binary data

This feature allows you to decode a string that was encoded in a custom base back into binary data. The example demonstrates decoding a base58 string back to its original binary form.

"const baseX = require('base-x');\nconst BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';\nconst bs58 = baseX(BASE58);\nconst decoded = bs58.decode('JxF12TrwUP45BMd');\nconsole.log(decoded); // Prints Buffer containing the original binary data"

Other packages similar to base-x

base58

The base58 npm package is specifically tailored for base58 encoding and decoding, similar to one of the use cases of base-x. However, base-x is more flexible as it supports custom bases, whereas base58 is fixed to the base58 alphabet.

bs58

bs58 is another package that provides similar functionality to base-x but is specifically for base58 encoding and decoding. It is less flexible than base-x because it does not allow for custom alphabets.

multibase

multibase is a package that supports multiple base encodings and is part of the multiformats family. It is more comprehensive than base-x as it supports a variety of bases out of the box and follows the multibase specification.

README

base-x

Fast base encoding / decoding of any given alphabet using bitcoin style leading zero compression.

Example

Base58

var BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
var bs58 = require('base-x')(BASE58)

var decoded = bs58.decode('5Kd3NBUAdUnhyzenEwVLy9pBKxSwXvE9FMPyR4UKZvpe6E3AgLr')

console.log(decoded)
// => [128,237,219,220,17,104,241,218,234,219,211,228,76,10,106,249,133,131,164,153,222,91,25,19,164,248,99]

console.log(Buffer.from(decoded))
// => <Buffer 80 ed db dc 11 68 f1 da ea db d3 e4 4c 1e 3f 8f 5a 28 4c 20 29 f7 8a d2 6a f9 85 83 a4 99 de 5b 19>

console.log(bs58.encode(decoded))
// => 5Kd3NBUAdUnhyzenEwVLy9pBKxSwXvE9FMPyR4UKZvpe6E3AgLr

Alphabets

See below for a list of commonly recognized alphabets, and their respective base.

Base	Alphabet
2	01
8	01234567
11	0123456789a
16	0123456789abcdef
32	0123456789ABCDEFGHJKMNPQRSTVWXYZ
36	0123456789abcdefghijklmnopqrstuvwxyz
58	123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz
62	0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
64	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
66	ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.!~

How it works

It encodes octet arrays by doing long divisions on all significant digits in the array, creating a representation of that number in the new base. Then for every leading zero in the input (not significant as a number) it will encode as a single leader character. This is the first in the alphabet and will decode as 8 bits. The other characters depend upon the base. For example, a base58 alphabet packs roughly 5.858 bits per character.

This means the encoded string 000f (using a 0-f alphabet) will actually decode to 4 bytes unlike a typical hex codec which uniformly packs 4 bits into each character.

While unusual, this does mean that no padding is required and it works for bases like 43. If you need standard hex encoding or base64 encoding you probably don't want this.

The algorithm used to convert the base of the number is roughly this:

significant =  12345
base = 16
digits = []
while significant > base:
  significant, remainder = divmod(significant, base)
  digits.append(remainder)
digits.append(significant)
assert list(reversed(digits)) == [3,0,3,9]
assert hex(12345) == '0x3039'

Of course the input is actually an array of digits already :)

License

This library is free and open-source software released under the MIT license.